home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / tcl / tcl70b2.lha / tcl7.0b2 / doc / array.n < prev    next >
Text File  |  1993-04-14  |  4KB  |  96 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/array.n,v 1.1 93/04/14 16:52:55 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS array tcl
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. array \- Manipulate array variables
  29. .SH SYNOPSIS
  30. \fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR?
  31. .BE
  32.  
  33. .SH DESCRIPTION
  34. .PP
  35. This command performs one of several operations on the
  36. variable given by \fIarrayName\fR.
  37. \fIArrayName\fR must be the name of an existing array variable.
  38. The \fIoption\fR argument determines what action is carried
  39. out by the command.
  40. The legal \fIoptions\fR (which may be abbreviated) are:
  41. .TP
  42. \fBarray anymore \fIarrayName searchId\fR
  43. Returns 1 if there are any more elements left to be processed
  44. in an array search, 0 if all elements have already been
  45. returned.
  46. \fISearchId\fR indicates which search on \fIarrayName\fR to
  47. check, and must have been the return value from a previous
  48. invocation of \fBarray startsearch\fR.
  49. This option is particularly useful if an array has an element
  50. with an empty name, since the return value from
  51. \fBarray nextelement\fR won't indicate whether the search
  52. has been completed.
  53. .TP
  54. \fBarray donesearch \fIarrayName searchId\fR
  55. This command terminates an array search and destroys all the
  56. state associated with that search.  \fISearchId\fR indicates
  57. which search on \fIarrayName\fR to destroy, and must have
  58. been the return value from a previous invocation of
  59. \fBarray startsearch\fR.  Returns an empty string.
  60. .TP
  61. \fBarray names \fIarrayName\fR
  62. Returns a list containing the names of all of the elements in
  63. the array.
  64. If there are no elements in the array then an empty string is
  65. returned.
  66. .TP
  67. \fBarray nextelement \fIarrayName searchId\fR
  68. Returns the name of the next element in \fIarrayName\fR, or
  69. an empty string if all elements of \fIarrayName\fR have
  70. already been returned in this search.  The \fIsearchId\fR
  71. argument identifies the search, and must have
  72. been the return value of an \fBarray startsearch\fR command.
  73. Warning:  if elements are added to or deleted from the array,
  74. then all searches are automatically terminated just as if
  75. \fBarray donesearch\fR had been invoked; this will cause
  76. \fBarray nextelement\fR operations to fail for those searches.
  77. .TP
  78. \fBarray size \fIarrayName\fR
  79. Returns a decimal string giving the number of elements in the
  80. array.
  81. .TP
  82. \fBarray startsearch \fIarrayName\fR
  83. This command initializes an element-by-element search through the
  84. array given by \fIarrayName\fR, such that invocations of the
  85. \fBarray nextelement\fR command will return the names of the
  86. individual elements in the array.
  87. When the search has been completed, the \fBarray donesearch\fR
  88. command should be invoked.
  89. The return value is a
  90. search identifier that must be used in \fBarray nextelement\fR
  91. and \fBarray donesearch\fR commands; it allows multiple
  92. searches to be underway simultaneously for the same array.
  93.  
  94. .SH KEYWORDS
  95. array, element names, search
  96.